Relaying information to client application

AI Agents and Flows can relay information to your client application during a conversation by emitting metadata events that are forwarded to your application as a SIP INFO message or HTTP POST request — useful to drive a live-agent desktop, a CRM screen-pop, analytics, or any side channel that should follow the conversation without affecting what the caller hears.

Each event the agent emits has the shape:

{
    "type": "event",
    "name": "sendMetaData",
    "value": { "category": "<category>", ... }
}

Only the value object is delivered to your application — not the full envelope — as the body of the SIP INFO message or HTTP POST request. The examples below show that value object for each category.

The category field (inside value) tells your application what produced the event:

Category	Produced by	See
`init`	the `send_metadata_init` config	Relaying the conversation identifiers
`transcript`	the `send_metadata_transcript` config	Relaying the conversation transcript
`event`	the `send_metadata_tools` agent config	Tools for sending metadata events
`tool`	a tool's `send_metadata` option	Relaying tool results
`webhook`	agent assist active mode with `transport: metadata`	Active agent assist mode

Configure how these events reach your application in the Bot Connection, as described in Sending metadata. For example, this Bot Connection parameter delivers the events as SIP INFO messages on the call:

{
    "sendMetadataAsSipInfo": true
}

Relaying the conversation identifiers

The send_metadata_init advanced configuration parameter relays the conversation identifiers to your application once, at the very beginning of the conversation — before the welcome message.

Use it when your application needs to fetch the conversation data once the call is over — its transcript, token usage or post-call-analysis results.

Parameter	Type	Description
`send_metadata_init`	bool	When `true`, relay a `sendMetaData` event carrying the conversation identifiers at the start of the conversation. Default: `false`.

Your application receives:

{
    "category": "init",
    "conversation_id": "<conversation id>",
    "call_id": "<call id>"
}

Example

{
    "send_metadata_init": true
}

Relaying the conversation transcript

The send_metadata_transcript advanced configuration parameter relays the running conversation transcript to your application. When enabled, every user utterance and every assistant response is relayed as a sendMetaData event — useful to follow the conversation in real time.

Parameter	Type	Description
`send_metadata_transcript`	bool	When `true`, relay each transcript line (user and assistant) as a `sendMetaData` event. Default: `false`.

Your application receives the speaker role and the text:

{
    "category": "transcript",
    "role": "user",
    "text": "<utterance>"
}

role – user for a user utterance, agent for the bot's response.
text – the utterance text.

Example

{
    "send_metadata_transcript": true
}

Tools for sending metadata events

The send_metadata_tools advanced configuration parameter lets you define AI Agent tools that, when called by the LLM, relay a metadata event to your application — for example, to report a detected intent.

Unlike a regular tool's send_metadata option, which relays the result of a tool that performs some action, the LLM calls these tools purely to emit the metadata event, and the conversation continues afterwards.

Parameter	Type	Description
`send_metadata_tools`	list[SendMetadataTool]	Defines tools that can be called by LLM to send a `sendMetaData` event.

SendMetadataTool

Parameter	Type	Description
`name`	str	Name of the tool. Must consist of English letters / digits / hyphens / underscores and be between 3 and 32 characters long.
`description`	str	Optional description of the tool. Provide a clear description that will help the LLM decide when to call the tool. You may also explicitly reference your tool (by name or description) in the prompt.
`params`	list[Param]	Optional parameters the LLM must provide when calling the tool. The supplied values are forwarded as the `data` of the metadata event.

Param

Parameter	Type	Description
`name`	str	Parameter name.
`type`	str	Parameter type: `str` (default), `int`, `float`, `bool`, `list[str]`, `list[int]`, `list[float]` or `list[bool]`.
`required`	bool	Whether the parameter is required. Default: `true`.
`description`	str	Parameter description that helps the LLM provide the right value. To restrict the value to a fixed set, start the description with `ENUM:` followed by a comma-separated list, e.g. `ENUM: refund, billing, support` (supported for `str`, `int`, `list[str]` and `list[int]` types).

When the LLM calls the tool, your application receives (category event):

{
    "category": "event",
    "name": "<tool name>",
    "data": { "<name>": "<value>" }
}

name – the name of the tool the LLM called.
data – the values the LLM supplied for the tool's params. Parameters whose name contains secret or token (case-insensitive) are excluded, for security reasons. Empty when the tool defines no params.

Example

{
    "send_metadata_tools": [
        {
            "name": "report_intent",
            "description": "Report the detected user intent",
            "params": [
                {
                    "name": "intent",
                    "type": "str",
                    "description": "ENUM: refund, billing, support. The type of assistance the user is requesting."
                }
            ]
        }
    ]
}

Relaying tool results

A tool can relay its result to your application after it runs, so the application can display some of the tool's parameters or response.

For example, a tool that searches an external database can return the source links behind its result, so your application can display them as citations alongside the agent's response.

Enable this by setting the send_metadata parameter on the tool's Advanced tab:

{
    "send_metadata": true
}

When enabled, after a successful tool call your application receives (category tool):

{
    "category": "tool",
    "name": "<tool name>",
    "params": { "<name>": "<value>" },
    "response": "<tool response>"
}

name – the name of the tool that ran.
params – the parameters the tool was called with. Parameters whose name contains secret or token (case-insensitive) are excluded, so credentials are never forwarded.
response – the tool's response. It is the original response, before any Response reshape is applied. When the response is valid JSON it is sent as JSON; otherwise it is sent as a string.

The event is sent for REST, MCP and Flow tools.

For tools that run in the background (the Wait for response parameter is off), the event is sent once the tool actually completes — after the agent has already continued the conversation.